#
# forth-83.hlp ---	online help strings for FORTH-83
#			compatiblity words in pfe
# (duz 13Sep94)
#

: 2+ ( n1 --- n2 ) [FORTH-83]
increments the top of stack by two.


: 2- ( n1 --- n2 ) [FORTH-83]
decrements the top of stack by two.


: COMPILE ( ``<spaces>name'' --- ) [FORTH-83]
Using COMPILE in interpretive state is an error.

In pfe COMPILE is immediate. COMPILE actively parses the next word and
adds the following compilation semantics to the current definition: To
compile this next word when the current definition is later executed.
The current definition is typically itself immediate and becomes
executed when comiling.

In ANS-Forth COMPILE is superseded by POSTPONE.


: VOCABULARY ( ``<spaces>name'' --- ) [FORTH-83]
parses name delimited by spaces. Creates a definition for name along
with an associated new words list. The execution semantics of the new
word name is to replace the first word list in the search order by
it's associated words list.


: ?BRANCH ( flag --- ) [FORTH-83]
low level control flow primitive. Executing this word in interpretive
state is a fatal error.

?BRANCH is the execution semantics of IF, WHILE and UNTIL. It takes
the cell compiled next and uses it as offset to add to the instruction
pointer conditionally. This results in a branch that takes place when
flag is 0, else execution continues with the next word compiled after
the offset.


: BRANCH ( --- ) [FORTH-83]
low level control flow primitive. Executing this word in interpretive
state is a fatal error.

BRANCH is the execution semantics of ELSE, REPEAT and AGAIN. It takes
the cell compiled next and uses it as offset to add to the instruction
pointer unconditionally. This results in a branch to the location
<instruction pointer after BRANCH + contents of following cell>.


: <MARK ( --- dest ) [FORTH-83]
same as HERE but can only be used compiling. Used by the first of a
pair of control flow words to pass a backward branch destination to
the second word. This second word typically uses <RESOLVE to compile
the backward branch offset.


: MARK> ( --- orig ) [FORTH-83]
used by the first of a pair of control flow words that involve a
forward branch. Compiles an empty location for a branch offset and
passes this location to the second word. This second word typically
uses RESOLVE> to fill in the branch destination.


: <RESOLVE ( dest --- ) [FORTH-83]
used by the second of a pair of control flow words that involve a
backward branch. Compiles the branch offset to the location dest.
Typically dest was provided by <MARK.


: RESOLVE> ( orig --- ) [FORTH-83]
used by the second of a pair of control flow words that involve a
forward branch. orig was typically provided by MARK> and points to a
location where an offset to the current location can be stored.


: --> ( --- ) [FORTH-83]
used when loading blocks. Continues interpretation or compilation with
the next block ignoring any text following in the current block.


: K ( --- n ) [FORTH-83]
Using K in interpretive state is an error.
When compiled, K puts the second outer loop index on the stack.
Use only inside at least three nested loops.


: OCTAL ( --- ) [FORTH-83]
Sets the number conversion base to 8.


: SP@ ( --- addr ) [FORTH-83]
returns the address of the top of the stack before executed.
You could define : DUP SP@ @ ;


: !BITS ( x1 a-addr x2 --- ) [FORTH-83]
stores the value of x1 masked by x2 into the equivalent masked part of
the cell at a-addr, without affecting bits outside the mask.


: @BITS ( a-addr x1 --- x2 ) [FORTH-83]
returns the contents of the cell at a-addr masked by x2.


: ** ( n1 n2 --- n3 ) [FORTH-83]
n3 is the value of n1 to the power n2.


: >< ( x1 --- x2 ) [FORTH-83]
swaps the two least significant bytes in x1 giving x2.


: >MOVE< ( addr1 addr2 u --- ) [FORTH-83]
moves u bytes starting at addr1 to the memory at addr2. During this
move, the order of each byte pair is reversed.


: SEAL ( --- ) [FORTH-83]
deletes all occurences of ONLY from the search order. The effect is
that only specified application vocabularies will be searched and the
search order cannot be changed any more.


# : >BODY ( xt --- a-addr ) [FORTH-83]
# xt is an execution token. a-addr is the address in the data space that
# belongs to the execution token. Since in pfe there is one contiguous
# region for definitions and data this is just the next cell and >BODY is
# equivalent to CELL+.


: >NAME ( xt --- c-addr ) [FORTH-83]
xt is an execution token. c-addr is the address of the count byte of
the name of the definition represented by xt. In the one contiguous
region that makes up the dictionary and data space in pfe the name
preceeds the execution token. Thus >NAME has to scan backward for the
beginning of the name. This beginning is marked by a count byte with
the most significant bit set. There is a low probability that >NAME
fails to detect the beginning of the name correctly when you use
characters with codes greater than 127 in the definition's name.


: >LINK ( xt --- a-addr ) [FORTH-83]
xt is an execution token. a-addr is a pointer to a cell in the header
of the word xt represents. In this cell a pointer is stored to the
name of another preceeding word in the dictionary. Using this pointer
pfe links words to word lists. However there are multiple linked list
for one word list. Thus it isn't sufficient to follow one thread of
links when all words in a word list shall be visited.


: BODY> ( a-addr --- xt ) [FORTH-83]
provided a-addr is the address of the first cell in the data space of
a definition then xt is the execution token of this definition. In the
one contiguous region where pfe keeps definitions and data an xt
preceeds the data space of the definition. Thus BODY> is equivalent to
`1 CELLS -'.


: NAME> ( c-addr --- xt ) [FORTH-83]
given a pointer to the count byte of the name inside a definition in
the dictionary, NAME> returns the execution token for that definition.
See also >NAME.


: LINK> ( a-addr --- xt ) [FORTH-83]
given the address inside a definition where pfe keeps the pointer to
the preceeding definition, LINK> returns the execution token for the
definition. See also >LINK.


: N>LINK ( c-addr --- a-addr ) [FORTH-83]
given a pointer to the name inside a definition in the dictionary,
N>LINK returns the address inside the definitions where pfe keeps the
pointer to the preceeding definition. See also >LINK.


: L>NAME ( a-addr --- c-addr ) [FORTH-83]
given the address inside a defintion where pfe keeps the pointer to
the preceeding definition, L>NAME returns the address of the count
byte of the name of the definition. See also >NAME.
